home *** CD-ROM | disk | FTP | other *** search
/ PC Bible Atlas / PC Bible Atlas.iso / dde.tx$ / DDE.TXT
Encoding:
Text File  |  1996-01-16  |  14.2 KB  |  319 lines
  1. PC Bible Atlas for Windows
  2. Dynamic Data Exchange Specification
  3. January, 1996
  4.  
  5. *********************************************************************
  6.                         INTRODUCTION
  7. *********************************************************************
  8.  
  9. This document specifies the Dynamic Data Exchange (DDE) support 
  10. provided by PC Bible Atlas for Windows (PCBA/Win).  DDE is a method 
  11. whereby two applications can communicate with one another using a 
  12. standardized format.  The two applications can share data as well as 
  13. send and respond to commands that specific actions be performed. 
  14.  
  15. In every DDE conversation, one application is called the "client 
  16. application" and the other is called the "server application."  The 
  17. client is the application that begins the conversation, requests data 
  18. from the other application, and sends commands to the other 
  19. application.  The server application is the application that provides 
  20. data to the client or that performs actions requested by the client.  
  21. PC Bible Atlas for Windows is capable of being both a DDE client and a 
  22. DDE server.  For example, when PC Bible Atlas requests that QuickVerse 
  23. for Windows (QV/Win) show a map containing a city, then PC Bible Atlas 
  24. is acting as a DDE client.  When another program requests that 
  25. PC Bible Atlas perform a search for a location, PC Bible Atlas acts as 
  26. a DDE server.  This document provides specifications for both server 
  27. and client DDE capability supported by PC Bible Atlas.
  28.  
  29. For specific information on using DDE with PC Bible Atlas and another 
  30. application, refer to this document and the other application's 
  31. documentation.  For specific information on how to write your own 
  32. program that uses DDE, refer to chapter 15 of the Windows Software 
  33. Developer Kit (SDK) volume 2 and chapter 17 of "Programming Windows 
  34. 2nd edition" by Charles Petzold. 
  35.  
  36.  
  37. *********************************************************************
  38.                         SERVER SPECIFICATION
  39. *********************************************************************
  40.  
  41. GENERAL METHODOLOGY
  42. -------------------
  43.  
  44. PC Bible Atlas supports "cold" DDE links.  Cold links allow 
  45. information to be passed from one application to another without any 
  46. additional updating being required or requested.  Warm links and hot 
  47. links are not required and are not supported. 
  48.  
  49. PC Bible Atlas responds to the application name "PCBAWIN" and the 
  50. topic name of "Commands."  PC Bible Atlas primarily uses the 
  51. WM_DDE_EXECUTE command and responds to a variety of instructions 
  52. (also called commands) passed with the WM_DDE_EXECUTE command.
  53.  
  54. PC Bible Atlas responds to all WM_DDE_EXECUTE messages with a 
  55. WM_DDE_ACK acknowledgement.  A negative acknowledgement is sent if the 
  56. command could not be completed; a positive acknowledgement indicates 
  57. that the command was completed.  
  58.  
  59. SPECIFICATION FOR WM_DDE_EXECUTE
  60. --------------------------------
  61.  
  62. The WM_DDE_EXECUTE message is used to pass commands to PC Bible Atlas.  
  63. These commands can cause PCBA/Win to perform a specific action (such 
  64. as a search for a location) or to provide information back to the 
  65. caller (such as a version number).  In all cases, the item string 
  66. contains the command string.  The command string is one or more 
  67. execute commands and any of their associated parameters.  
  68.  
  69. The following execute commands are supported.  The Syntax Version 
  70. column specifies the syntax version of each command, and the Program 
  71. Version column indicates which version of PC Bible Atlas first supported 
  72. the command.  Detailed descriptions of these command are provided in a 
  73. later section.
  74.  
  75.                                     Syntax          Program
  76.     Execute Command                 Version         Version
  77.     --------------------------------------------------------
  78.     [Minimize]                         1              1.0c
  79.     [Activate]                         1              1.0c
  80.     [Show("location name")]            1              1.0c
  81.     [LoadProgVersion(hmem)]            1              1.0c
  82.     [LoadSyntaxVersion(hmem)]          1              1.0c
  83.  
  84. The syntax version is used to inform the client application about the 
  85. commands that are supported by the running version of PCBA/Win. For 
  86. instance, if a client application wants to send a "level 2 syntax" 
  87. command to PC Bible Atlas, it may first determine if it supports that 
  88. level of syntax.  All levels are "backwards" compatible, so a program 
  89. capable of support level 2 syntax also supports all level 0 and level 
  90. 1 commands. 
  91.  
  92. Each command must be enclosed by brackets [ ] and each command may be 
  93. separated by a space.  Spaces within each command are not allowed, 
  94. except in quoted strings.  Parenthesis ( ) are used to begin and end 
  95. the parameter list.  All parameters are passed as strings and decoded 
  96. depending upon the execute command.  String parameters are expected to 
  97. be enclosed by double-quotes, so the string parameter may not contain 
  98. a double quote character.  Parenthesis within quoted parameters are 
  99. allowed. 
  100.  
  101. Multiple commands may be passed in one command string.  For instance, 
  102. to both activate PC Bible Atlas and ask it to search for the location 
  103. Jerusalem, the following command string could be used
  104.  
  105.     [Activate][Show("Jerusalem")]
  106.  
  107. if multiple commands are contained in one item, the commands will be 
  108. processed from left to right.  The process will abort and return a 
  109. negative acknowledgement immediately upon encountering an error.  That 
  110. is, if the command string is
  111.  
  112.     [Activate][Show("Jerusalem")]
  113.  
  114. and the activation can not be performed, then the Show command will 
  115. never be executed.
  116.  
  117. Additional details about each command are provided below.
  118.  
  119.     Application:    PCBAWIN
  120.     Topic:          Commands
  121.     Item:           [Minimize]
  122.     Example:        [Minimize]        
  123.     Syntax Level:   1
  124.  
  125.         This command causes the whole PC Bible Atlas application to be 
  126.         minimized (i.e. made into an icon), but does not activate it. 
  127.  
  128.     Application:    PCBAWIN
  129.     Topic:          Commands
  130.     Item:           [Activate]
  131.     Example:        [Activate]        
  132.     Syntax Level:   1
  133.  
  134.         This command causes PC Bible Atlas to be activated.  If it is 
  135.         minimized, it is also restored to normal size.
  136.  
  137.     Application:    PCBAWIN
  138.     Topic:          Commands
  139.     Item:           [Show("location name")]
  140.     Example:        [Activate][Show("Jerusalem")]        
  141.     Syntax Level:   1
  142.  
  143.         This command is used to cause PC Bible Atlas to locate the
  144.         maps containing the specified location.  A list of maps
  145.         containing the location is displayed, and the user can 
  146.         select which map to view the location on.
  147.  
  148.         The phrase is passed as a string, so it must be enclosed by 
  149.         double-quotes.  
  150.  
  151.         It is typical to use the Activate command with this message to 
  152.         ensure that PC Bible Atlas for windows is activated following
  153.         the search.
  154.  
  155.     Application:    PCBAWIN
  156.     Topic:          Commands
  157.     Item:           [LoadProgVersion(hmem)]
  158.     Example:        [LoadProgVersion(1234)]        
  159.     Syntax Level:   1
  160.  
  161.         This command causes PC Bible Atlas to load the string 
  162.         identified by the memory handle "hmem" with the version of 
  163.         PC Bible Atlas that is running.  hmem is converted from a 
  164.         string value into an unsigned integer (memory handle) with 
  165.         little error checking provided.  An error occurs if hmem is 
  166.         not a valid memory handle, or if the memory it references is 
  167.         not large enough to contain the version string.  The version 
  168.         string is something like "1.0c" where 1.0 is the major version 
  169.         number and the last letter is the minor revision letter. 
  170.  
  171.     Application:    PCBAWIN
  172.     Topic:          Commands
  173.     Item:           [LoadSyntaxVersion(hmem)]
  174.     Example:        [LoadSyntaxVersion(1234)]        
  175.     Syntax Level:   1
  176.  
  177.         This command causes PC Bible Atlas to load the syntax version 
  178.         that it supports into the memory identified by "hmem."  hmem 
  179.         is converted from a string value into an unsigned integer 
  180.         (memory handle) with little error checking provided.  An error 
  181.         occurs if hmem is not a valid memory handle.  The memory 
  182.         identified is loaded with an integer value (i.e. not a string 
  183.         representation of an integer) such as 1, 2, etc. 
  184.  
  185.         It is recommended that client applications use this command to 
  186.         determine if PC Bible Atlas supports the commands that the 
  187.         client supports or requires.
  188.  
  189. As previously noted, PC Bible Atlas will respond to the WM_DDE_EXECUTE 
  190. messages with a WM_DDE_ACK message.  A positive acknowledgement is 
  191. sent when the command was successful; a negative acknowledgement is 
  192. sent otherwise.  Information about the WM_DDE_ACK message and error 
  193. handling is provided in a following section. 
  194.  
  195. Additional commands may be added in later editions of PC Bible Atlas.  
  196. If so, these commands will be identified with a new syntax version.  
  197. This allows a client application to determine which commands are 
  198. available before trying to use one. 
  199.  
  200. ERROR HANDLING
  201. --------------
  202.  
  203. The client application can generally rely upon PC Bible Atlas to 
  204. display an error message that describes the error condition.  
  205.  
  206. In addition, PC Bible Atlas responds to all WM_DDE_EXECUTE messages
  207. with a WM_DDE_ACK message.  A DDEACK structure accompanies the 
  208. acknowledge message.  This structure contains 3 fields of interest:  
  209. fAck, fBusy, and bAppReturnCode.  The fAck flag contains the 
  210. acknowledgement.  A positive acknowledgement is sent if the command 
  211. string was completely executed; otherwise a negative acknowledgement 
  212. is sent.  The remaining two fields contain information about the 
  213. failure, since there may be many reasons that the commands were not 
  214. completed. 
  215.  
  216. The client application should not assume that the command was 
  217. unrecognized if a negative acknowledgement was received.  If a 
  218. negative acknowledgement is received, the client application should 
  219. first examine the fBusy flag.  If this flag is set, then PC Bible 
  220. Atlas did not execute the commands because it was busy.  PC Bible 
  221. Atlas can be "busy" when it is in a modal state (i.e. when an error 
  222. message or modal dialog box is displayed) or when under any other 
  223. condition when it is unable to process the DDE command due to the 
  224. state of the program.
  225.  
  226. The bAppReturnCode field is used to contain additional information 
  227. about why a negative acknowledgement was received.  PC Bible Atlas 
  228. does not current use this field so its value is undefined.
  229.  
  230.  
  231. *********************************************************************
  232.                         CLIENT SPECIFICATION
  233. *********************************************************************
  234.  
  235. GENERAL METHODOLOGY
  236. -------------------
  237.  
  238. PC Bible Atlas can serve as a DDE client application and pass instructions 
  239. to other applications with the WM_DDE_EXECUTE command.
  240.  
  241. SPECIFICATION FOR THE INTERFACE TO A BIBLE PROGRAM
  242. --------------------------------------------------
  243.  
  244. A PC Bible Atlas user can choose the Bible Study program that PC Bible 
  245. Atlas interacts with.  While this is designed to allow interaction 
  246. with QuickVerse for Windows (version 1.0i and newer), any Bible Study 
  247. package that supports the following WM_DDE_EXECUTE commands can be 
  248. used.
  249.  
  250.     Application:    User defined
  251.     Topic name:     Verses
  252.  
  253.                                 Syntax          Program Version
  254.     Item                        Level           Used In
  255.     ------------------------------------------------------------
  256.     [Activate]                      1           1.0c
  257.     [QuickSearch("phrase")]         1           1.0c
  258.     [RefSearch("reference")]        1           1.0c
  259.     [GoTo("ref")]                   1           1.0c
  260.     [LoadCurrentTranslation(hmem)   1           1.0c
  261.  
  262. Refer to the DDE Specification for QuickVerse for Windows for more 
  263. detail regarding these specific commands.
  264.  
  265. One important note is that PC Bible Atlas expects a WM_DDE_ACK message 
  266. to be received within a specified period after sending the execute 
  267. command.  If the message is not received, PC Bible Atlas will issue a 
  268. time-out and report that the operation has failed.
  269.  
  270. PC Bible Atlas checks the returned acknowledgement for a positive or 
  271. negative acknowledgement, as well as the busy flag as appropriate.  It 
  272. does not check the bAppReturnCode flag. 
  273.  
  274. SPECIFICATION FOR THE INTERFACE TO A BIBLE DICTIONARY
  275. -----------------------------------------------------
  276.  
  277. A PC Bible Atlas user can choose the dictionary program that PC Bible Atlas 
  278. interacts with.  While PC Bible Atlas is designed to be used with the
  279. Holman Bible Dictionary, any dictionary that supports the following
  280. WM_DDE_EXECUTE commands may be used.
  281.  
  282.     Application:    User defined
  283.     Topic name:     Commands
  284.  
  285.                                 Syntax          Program Version
  286.     Item                        Level           Used In
  287.     ------------------------------------------------------------
  288.     [Show("item")]              1               1.0i
  289.     [Activate]                  1               1.0i
  290.     [LoadSyntaxVersion(hmem)]   1               1.0i
  291.  
  292. Refer to the DDE Specification for the Holman Bible Dictionary
  293. for more detail regarding these specific commands.
  294.  
  295. SPECIFICATION FOR THE INTERFACE TO THE QUICKVERSE LIBRARY
  296. ---------------------------------------------------------
  297.  
  298. PC Bible Atlas is designed to be used with the QuickVerse Library, 
  299. but it can be used with any reference library that supports
  300. the following commands.
  301.  
  302.     Application:    User defined
  303.     Topic name:     Commands
  304.  
  305.                                        Syntax          Program Version
  306.     Item                               Level           Used In
  307.     ------------------------------------------------------------
  308.     [Activate]                         1               1.0j
  309.     [WordSearch("word","language")]    1               1.0j
  310.     [WordSync("word")]                 1               1.0j
  311.     [VerseSearch("ref")]               1               1.0j
  312.     [VerseSync("ref")]                 1               1.0j
  313.  
  314. Refer to the DDE Specification for the QuickVerse Library
  315. for more detail regarding these specific commands.
  316.  
  317.  
  318.  
  319.